 /*******************************************************************************
  * Copyright (c) 2004, 2006 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  *******************************************************************************/
 package org.eclipse.ui.internal.preferences;

 import java.util.Set ;

 /**
  * Eclipse provides many different classes and interfaces that map ids onto values and
  * send property change notifications (some examples are themes, preference stores,
  * xml nodes, property providers, and others). This interface is intended to provide
  * interoperability between these various classes.
  *
  * @since 3.1
  */
 public interface IPropertyMap {
     
     /**
      * Returns the set of keys that are recognized by this property map
      * (optional operation).
      *
      * @return the set of valid keys for this map
      * @throws UnsupportedOperationException if this type of property map
      * cannot compute the set of valid keys
      * @since 3.1
      */
     public Set keySet();
     
     /**
      * Returns the value of the given property. Returns null if the given
      * property does not exist, cannot be converted into the expected type,
      * or if the value of the property is null.
      *
      * @param propertyId property ID to query
      * @param propertyType type of the expected return value
      * @return an object of the given propertyType or null if the property
      * does not exist or has the wrong type
      * @since 3.1
      */
     public Object getValue(String propertyId, Class propertyType);
     
     /**
      * If this map represents the union of multiple property maps, this
      * returns true iff the property existed in every map in the union.
      * Always returns true if this map was not computed from the union
      * of multiple maps.
      *
      * @param propertyId
      * @return true iff the given property existed in every child map
      * @since 3.1
      */
     public boolean isCommonProperty(String propertyId);
     
     /**
      * Returns true iff the given property exists.
      *
      * @param propertyId
      * @return true iff the given property exists in this map
      * @since 3.1
      */
     public boolean propertyExists(String propertyId);
       
     /**
      * Sets the value of the given property to the given value (optional
      * operation).
      *
      * @param propertyId
      * @param newValue
      * @throws UnsupportedOperationException if this type of property map
      * is read-only
      * @since 3.1
      */
     public void setValue(String propertyId, Object newValue);
 }

